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CP/M INTERFACE GUIDE 



1. INTRODUCTION 



This manual describes the CP/M system organization including 
the structure of memory, as well as system entry points. The 
intention here is to provide the necessary information required 
to write programs which operate under CP/M, and which use the 
peripheral and disk l/O facilities of the system. 

1.1 CP/M Organization 

CP/M is logically divided into four parts: 

BIOS - the basic I/O system for serial peripheral control 

BDOS - the basic disk operating system primitives 

CCP - the console command processer 

TPA -• the transient program area 

The BIOS and BDOS are combined into a single program with a com- 
mon entry point and referred to as the FDOS. The CCP is a dis- 
tinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the diskette. 
The TPA is an area of memory (i.e, the portion which is not used 
by the FDOS and CCP) where various non-resident operating system 
commands are executed. User programs also execute in the TPA. 
The organization of memory in a standard CP/M system is shown in 
Figure 1. 

The lower portion of memory is reserved for system information 
(which is detailed in later sections) , including user defined inter- 
rupt locations. The portion between tbase and cbase is reserved 
for the transient operating system commands, while the portion 
above cbase contains the resident CCP and FDOS. The last three 
locations of memory contain a jump instruction to the FDOS entry 
point which provides access to system functions. 

1.2 Operation of Transient Programs 

Transient programs (system functions and user-defined programs) 
are loaded into the TPA and executed as follows. The operator 
communicates with the CCP by typing command lines following each 
prompt character. Each command line takes one of the forms: 

"^command^ 

<command> <filename> 

^ommand> <f ilename'* ,<f iletype> 



Figure 1. CP/M Memory Organization 



fbase: 



cbase: 



tbase : 



boot: 



FDOS 



CCP 
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System Parameters 
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F 



address field of jump is fbase 



entry: 



the principal entry point to FDOS is at location 0005 
which contains a JMP to fbase. The address field at 
location 0006 can be used to determine the size of 
available memory, assuming the CCP is being overlayed. 



Note: The exact addresses for boot, tbase, cbase, fbase, 
and entry vary with the CP/M version (see 
Section 6. for version correspondence) . 



Where <cominand> is either a built-in command (e.g., DIR or TYPE), 
or the name of a transient command or program. If the <command> 
is a built-in function of CP/M, it is executed immediately; other- 
wise the CCP searches the currently addressed disk for a file 
by the name 

< command > . COM 

If the file is found, it is assumed to be a memory image of a 
program which executes in the TPA, and thus implicitly originates 
at tbase in memory (see the CP/M LOAD command) . The CCP loads 
the COM file from the diskette into memory starting at tbase, 
and extending up to address cbase. 

If the <command> is followed by either a <filename> or 
<filename>. <f iletype>, then the CCP prepares a file control- 
block (FCB) in the system information area of memory. This FCB 
is in the form required to access the file through the FDOS, and 
is given in detail in Section 3.2. 

The program then executes, perhaps using the I/O facilities 
of the FDOS. If the program uses no FDOS facilities, then the 
entire remaining memory area is available for data used by the 
program. If the FDOS is to remain in memory, then the transient 
program can use only up to location fbase as data.* In any case, 
if the CCP area is used by the transient, the entire CP/M system 
must be reloaded upon the transient's completion. This system 
reload is accomplished by a direct branch to location "boot" in 
memory. 

The transient uses the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including 
the floppy disk subsystem. The I/O system is accessed by passing 
a "function number" and an "information address" to CP/M through 
the address marked "entry" in Figure 1. In the case of a disk 
read, for example, the tramsient program sends the number corres- 
ponding to a disk read, along with the address of an FCB, and 
CP/M performs the operation, returning with either a disk read 
complete indication or an error number indicating that the disk 
operation was unsuccessful. The function numbers and error in- 
dicators are given in detail in Section 3.3. 

1.3 Operating System Facilities 

CP/M facilities which are available to transients are divided 
into two categories: BIOS operations, and BDOS primitives. The 
BIOS operations are listed first:** 

* Address "entry" contains a jump to the lowest address in the 
FDOS, and thus "entry+1" contains the first FDOS address which 
cannot be overlayed. 

**The device support (exclusive of the disk subsystem) corres- 
ponds exactly to Intel's peripheral definition, including I/O 
port assignment and status byte format (see the Intel manual 
which discusses the Ittteliec MDS hardware environment) . 



Read Console Character 
Write Console Character 
Read Reader Character 
Write Punch Character 
Write List Device Character 
Set I/O Status 
Interrogate Device Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Status 

The exact details of BIOS access are given in Section 2. The BDOS 
primitives include the following operations: 

Disk System Reset 

Drive Select 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Read Record 

Write Record 

Interrogate Available Disks 

Interrogate Selected Disk 

Set DMA Address 

The details of BDOS access are given in Section 3. 

2. BASIC I/O FACILITIES 

Access to common peripherals is accomplished by passing a 
function number and information address to the BIOS. In general, 
the function number is passed in Register C, while the informa- 
tion address is passed in Register pair D,E. Note that this 
conforms to the PL/M Conventions for parameter passing, and thus 
the following PL/M procedure is sufficient to link to the BIOS 
when a value is returned: 

DECLARE ENTRY LITERALLY '0005H'; /* MONITOR ENTRY */ 

'" M0N2: PROCEDURE (FUNC, INFO) BYTE; 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 

END M0N2; 



or 

MONl: PROCEDURE (FUNCINFO); 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 
END MONl 

if no returned value is expected. 

2.1 Direct and Buffered l/O. 

The BIOS entry points are given in Table I. In the case of 
simple character I/O to the console, the BIOS reads the console 
device, and removes the parity bit. The character is echoed back 
to the console, and tab characters (control-I) are expanded to 
tab positions starting at column one and separated by eight char- 
acter positions. The I/O status byte takes the form shown in 
Table I, and can be programmatic ally interrogated or changed. 
The buffered read operation takes advantage of the CP/M line edit- 
ing facilities. That is, the program sends the address of a read 
buffer whose first byte is the length of the buffer. The second 
byte is initially empty, but is filled-in by CP/M to the number 
of characters read from the console after the operation (not 
including the terminating carriage-return) . The remaining posi- 
tions are used to hold the characters read from the console. The 
BIOS line editing functions which are performed during this oper- 
ation are given below: 

break - line delete and transmit 

rubout - delete last character typed, and echo 

control-C - system rebout 

control-U - delete entire line 

control-E - return carriage, but do not transmit 
buffer (physical carriage return) 

<cr> - transmit buffer 

The read routine also detects control character sequences other 
than those shown above, and echos them with a preceding "t" 
symbol. The print entry point allows an entire string of symbols 
to be printed before returning from the BIOS. The string is 
terminated by a "$" symbol. 

2.2 A Simple Example 

As an example, consider the following PL/M procedures and 
procedure calls which print a heading, and successively read 
the console buffer. Each console buffer is then echoed back in 
reverse order: 



PRINTCHAR: PRCXTEDURE (B) ; 

/* SEND THE ASCII CHARACTER B TO THE CONSOliE */ 
DECLARE B BYTE ; 
CALL MONK 2 /B) ; 
END PRINTCHAR; 



CRLF: PROCEDURE; 

/* SEND CARRIAGE-RETURN-LINE-FEED CHARACTERS */ 
CALL PRINTCHAR (ODH); CALL PRINTCHAR (OAH) ; 
END CRLF; 



PRINT: PROCEDURE (A); 

/* PRINT THE BUFFER STARTING AT ADDRESS A */ 
DECLARE A ADDRESS; 
CALL M0N1(9,A) ; 
END PRINT; 

DECLARE RDBUFF (130) BYTE; 

READ: PROCEDURE; 

/* READ CONSOLE CHARACTERS INTO 'RDBUFF' */ 
RDBUFF=128; /* FIRST BYTE SET TO BUFFER LENGTH */ 
CALL MONl (10, .RDBUFF) ; 
END READ; 

DECLARE I BYTE; 

CALL CRLF; CALL PRINT (.'TYPE INPUT LINES $'); 

DO WHILE 1; /* INFINITE LOOP-UNTIL CONTROL-C */ 
CALL CRLF; CALL PRINTCHAR ('*'); /* PROMPT WITH '*' */ 
CALL READ; I = RDBUFF(l); 

DO WHILE (I := I -1) <> 255; 

CALL PRINTCHAR (RDBUFF (1+2) ); 

END; 
END; 

The execution of this program might proceed as follows: 

TYPE INPUT LINES 

*HELLOj 

OLLEH 

♦WALL WALLA WASH . 

HSAW ALLAW ALLAW 

*MOM WOW^ 

WOW MOM 

*tc (system reboot) 



TABLE I 
BASIC I/O OPERATIONS 



FUNCTION/ 
NUMBER 


ENTRY 
PARAMETERS 


RETURNED 
VALUE 


TYPICAL 
CALL 


^ead Console 
1 


None 


ASCII Character 


I = MON2(1,0) 


J^rite Console 
2 


ASCII Character 


None 


CALL M0N1(2, 'A") 


:^ead Reader 
3 


None 


ASCII Character 


I == MON2(3,0) 


f^rite Punch 
4 


ASCII Character 


None 


CALL M0N1(4, 'B') 


/vFrite List 
5 


ASCII Character 


None 


CALL MONl ( 5 , • C • ) 


Set I/O Status 
7 


None 


I/O Status Byte 


IOSTAT=MON2(7,0) 


Set I/O Status 
8 


I/O Status Byte 


None 


CALL MONl (8, lOSTAT) 


Print Buffer 
9 


Address of 
string termi- 
nated by '$' 


None 


CALL MONl (9, . 'PRINT 
THIS $') 




\ 


i 


'. 



4? ~" H*^- 



HL 



TABLE I (continued) 



FUNCTION/ 
NUMBER 


ENTRY 
PARAMETERS 


RETURNED 
VALUE 


TYPICAL 
CALL 


Read Buffer 
10 


Address of 
Read Buffer* 

(See Note,) 


Read buffer is 
filled to maxi- 
mum length with 
console charac- 
ters 


CALL MONK 10, 
. RDBUFF) ; 


Interrogate 
Console Ready 

11 


None 


Byte value with 
least signifi- 
cant bit = 1 
(true) if con- 
sole character 
is ready 


I = MON2(11,0) 



Note. 



Note. 



Read buffer is a sequence of memory locations of the form 



m k c 



T ^current buffer length 
' — Maximum buffer length 

The I/O status byte is defined as three fields A,B,C, and D 

2b 2b 2b 2b 



A B C D 



MSB 



LSB 



requiring two bits each, listed from most significant to least 
significant bit, which define the current device assignment as 
follows: 



D 
Console 



TTY ^ 

1 CRT \ 

2 BATCH I 



"0 TTY 
C = ; 1 FAST READER 
Reader \ 2 



'0 TTY 
B = J 1 FAST PUNCH 
Punch S 2 




3. DISK I/O FACILITIES 

The BDOS section of CP/M provides access to files stored on 
diskettes. The discussion which follows gives the overall file 
organization, along with file access mechanisms. 

3,1 File Organization 

CP/M implements a named file structure on each diskette, pro- 
viding a logical organization which allows any particular file to 
contain any number of records, from completely empty, to the full 
capacity of a diskette. Each diskette is logically distinct, 
with a complete operating system, disk directory, and file data 
area. The disk file names are in two parts: the <filename> 
which can be from one to eight alphanumeric characters, and the 
*^filetype> which consists of zero through three alphanumeric 
characters. The <filetype> names the generic category of a par- 
ticular file, while the <filename> distinguishes a particular 
file within the category. The <f iletype> s listed below give 
some generic categories which have been established, although 
they are generally arbitrary: 

ASM assembler source file 

PPN assembler listing file 

HEX assemblei^ or PL/M machine code 
in "hex" format 

BAS BASIC Source file 

INT BASIC Intermediate file 

COM Memory image file (i.e., "Command" 

file for transients, produced by LOAD) 

BAK Backup file produced by editor 
(see ED manual) 

$$$ Temporary files created and normally 
erased by editor and utilities 

Thus, the name 

X.ASM 

is interpreted as an assembly language source file by the CCP 
with <filename> X. 

The files in CP/M are organized as a logically contiguous se- 
quence of 128 byte records (although the records may not be phys- 
ically contiguous on the diskette) , which are normally read or 
written in sequential order. Random access is allowed under CP/M 
however, as described in Section 3.4. No particular format with- 
in records is assumed by CP/M, although some transients expect 
particular formats: 



and 
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(1) Source files are considered a sequence of 
ASCII characters, where each "line" of the 
source file is followed by carriage-return- 
line-feed characters. Thus, one 128 byte 
CP/m record could contain several logical 
lines of source text. Machine code "hex" 
tapes are also assumed to be in this for- 
mat, although the loader does not require 
the carriage-return-line-feed characters. 
End of text is given by the character con- 
trol-z, or real end-of-file returned by 
CP/m. 

(2) COM files are assumed to be absolute machine 
code in memory image form, starting at tbase 
in memory. In this case, control-z is not 
considered an end of file, but instead is 
determined by the actual space allocated 

to the file being accessed. 

3.2 File Control Block Format 

Each file being accessed through CP/M has a corresponding 
file control block (FCB) which provides name and allocation 
information for all file operations. The FCB is a 3 3 -byte area 
in the transient program's memory space which is set up for each 
file. The FCB format is given in Figure 2. When accessing CP/M 
files, it is the programmer's responsibility to fill the lower 
16 bytes of the FCB, along with the CR field. Normally, the FN 
and FT fields are set to the ASCII <filename> and <filetype>, 
while all other fields are set to zero. Each FCB describes up 
to 16K bytes of a particular file (0 to 128 records of 128 bytes 
each), and, using automatic mechanisms of CP/M, up to 15 addi- 
tional extensions of the file can be addressed. Thus, each FCB 
can potentially describe files up to 256K bytes (which is slightly 
larger than the diskette capacity). 

FCB's are stored in a directory area of the diskette, and are 
brought into central memory before file operations (see the OPEN 
and MAKE commands) then updated in memory as file operations pro- 
ceed, and finally recorded on the diskette at the termination of 
the file operation (see the CLOSE command) . This organization 
makes CP/M file organization highly reliable, since diskette file 
integrity can only be disrupted in the unlikely case of hardware 
failure during update of a single directory entry. 

It should be noted that the CCP constructs an FCB for all 
transients by scanning the remainder of the line following the 
transient name for a <filename> or <filenarae>.<f iletype> com- 
bination. Any field not specified is assumed to be all blanks. 
A properly formed FCB is set up at location tfcb (see Section 6), 
with an assumed I/O buffer at tbuff. The transient can use tfcb 
as an address in subsequent input or output operations on this 
file. 
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In addition to the default fob which is set-up at address tfcb, the 
CCP also constructs a second default fob at address tfcb+ 16 (i.e., the 
disk map field of the fob at tbase) . Thus, if the user types 

PRDGNAME X.ZOT Y.ZAP 

the file PPDGNAME.COM is loaded to the TPA, and the default fcb at . tf cb 
is initialized to the filename X with file type ZOT. Since the user typed 
a second file name, the 16 byte area beginning at tfcb^ + 16]lo ^^ also 
initialized with the filename Y and filetype ZAP. It is the responsibility 
of the program to move this second filename and filetype to another area 
(usually a separate file control block) before opening the file which 
begins at tbase, since the open operation will fill the disk map portion, 
thus overwriting the second name and type. 

If no file names were specified in the original command, then the 
fields beginning at tfcb and tfcb + 16 both contain blanks (20H) . If 
one file name was specified, then the field at tfcb + 16 contains blanks. 
If the filetype is omitted, then the field is assumed to contain blanks. 
In all cases, the CCP translates lower case alphabetics to upper case 
to be consistent with the CP/M file naming conventions. 

As an added programming convenience, the default buffer at tbuff 
is initialized to hold the entire command line past the program name. 
Address tbuff contains the niamber of characters, and tbuff+1, tbuff +2, 
..., contain the remaining characters up to, but not including, the 
carriage return. Given that the above command has been typed at 
the console, the area beginning at tbuff is set up as follows: 

tbuff: 

+0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11+12 +13 +14 +15 
12 J6 X . Z T JtJ- Y . ZAP ? ? ? 

where 12 is the number of valid characters (in binary) , and }& represents 
an ASCII blank. Characters are given in ASCII upper case, with un- 
initialized memory following the last valid character. 

Again, it is the responsibility of the program to extract the infor- 
mation from this buffer before any file operations are performed since 
the FDOS uses the tbuff area to perform directory functions. 

In a standard CP/M system, the following values are assumed: 

boot: OOOOH bootstrap load twarm start) 
entry point to FDOS ' 
first default file control block 
second file name 
default buffer address 
base of transient area 



entry: 


0005H 


tfcb: 


005CH 


tfcb+16 


006CH 


tbuff 


0080H 


tbase : 


OlOOH 
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Figure 2. File Control Block Format 
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ET 



FN 



FT EX RC 



DM 



NR 



FIELD 



ET 



FN 



FT 



EX 



RC 



DM 



NR 



FCB POSITIONS 



1-8 

9-11 

12 

13-14 
15 

16-31 

32 



PURPOSE 

Entry type (currently not used, 
but assumed zero) 

File name, padded with ASCII 
blanks 

File type, padded with ASCII 
blanks 

File extent, normally set to 
zero 

Not used, but assumed zero 

Record count is current extent 
Size (0 to 128 records) 

Disk allocation map, filled-in 
and used by CP/M 

Next record number to read or 
write 
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3.3 Disk Access Primitives 

Given that a program has properly initialized the FCB's for 
each of its files, there are several operations which can be per- 
formed, as shown in Table II. In each case, the operation is 
applied to the currently selected disk (see the disk select oper- 
ation in Table II), using the file information in a specific FCB, 
The following PL/M program segment, for example, copies the con- 
tents of the file X.Y to the (new) file NEW. FIL: 

DECLARE RET BYTE,.; 

OPEN: PROCEDURE (A) 

DECLARE A ADDl^ESS; 
RET=MON2(15,A) 7 
END OPEN; 

CLOSE: PROCEDURE (A); 

DECLARE A ADDRESS; 
RET=MON2(16,A) ; 
END; 



MAKE 



PROCEDURE (A) ; 
DECLARE A ADDRESS; 
RET=MON2(22,A) ; 
END MAKE; 



DELETE: PROCEDURE (A); 

DECLARE A ADDRESS; 

/* IGNORE RETURNED VALUE */ 

CALL M0N1(19,A) ; 

END DELETE; 

READBF: PROCEDURE (A) ; 

DECLARE A ADDRESS; 
RET=MON2(20,A) ; 
END READBF; 

WRITEBF: PROCEDURE (A); 

DECLARE A ADDRESS; 
RET=MON2(21,A) ; 
END WRITEBF; 



INIT: PROCEDURE; 

CALL MON1(13;0) ; 
END INIT; 

/* SET UP FILE CONTROL BLOCKS */ 
DECLARE FCBl (33) BYTE 

INITIAL (0, 'X S'Y ',0,0,0,0), 

FCB2 (33) BYTE 

INITIAL (0, 'NEW ', 'FIL' ,0, 0,0,0) ; 
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CALL INIT; 

/* ERASE 'NEW.FIL' IF IT EXISTS */ 
CALL DELETE (.FCB2); 

/* CREATE' 'NEW.FIL' AND CHECK SUCCESS */ 
CALL MAKE (.FCB2); 

IF RET = 255 THEN CALL PRINT (.'NO DIRECTORY SPACE $'); 
ELSE 

DO; /* FILE SUCCESSFULLY CREATED/NOW OPEN 'X.Y' */ 
CALL OPEN (.FCBl) ; 

IF RET = 255 THEN CALL PRINT (.'FILE NOT PRESENT $'); 
ELSE 

DO; /* FILE X.Y FOUND AND OPENED, SET 
NEXT RECORD TO ZERO FOR BOTH FILES */ 
FCB1(32), FCB2(32) = 0; 

/* READ FILE X.Y UNTIL EOF OR ERROR */ 
CALL READBF (.FCBl); /*READ TO 80H*/ 
DO WHILE RET = 0; 

CALL WRITEBF (.FCB2) /*WRITE FROM 80H*/ 
IF RET = THEN /*GET ANOTHER RECORD*/ 
CALL READBF (.FCBl); ELSE 
CALL PRINT (. 'DISK WRITE ERROR $•) ; 
END; 
IF RET < >1 THEN CALL PRINT (.' TRANSFER ERROR $*); 
ELSE 

DO; CALL CLOSE (.FCB2); 

IF RET = 255 THEN CALL PRINT (.'CLOSE ERROR$ ' ) ; 
END; 
END; 
END; 
EOF 

This program consists of a number of utility procedures for 
opening, closing, creating, and deleting files, as well as two 
procedures for reading and writing data. These utility procedures 
are followed by two FCB's for the input and output files. In 
both cases, the first 16 bytes are initialized to the <filename> 
and <filetype> of the input and output files. The main program 
first initializes the disk system, then deletes any existing 
copy of "NEW.FIL" before starting. The next step is to create 
a new directory entry (and empty file) for "NEW.FIL". If file 
creation is successful, the input file "X.Y" is opened. If this 
second operation is also successful, then the disk to disk copy 
can proceed. The NR fields are set to zero so that the first 
record of each file is accessed on subsequent disk I/O operations. 
The first call to READBF fills the (implied) DMA buffer at 80H 
with the first record from X.Y. The loop which follows copies 
the record at 80H to "NEW.FIL" and then reports any errors, or 
reads another 128 bytes from X.Y. This transfer operation con- 
tinues until either all data has been transferred, or an error 
condition arises. If an error occurs, it is reported; other- 
wise the new file is closed and the program halts. 



TABLE II 
DISK ACCESS PRIMITIVES 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Lift Head 
12 



None 



None 

Head is lifted from 

current drive 



CALL MON2(12,0) 



Initialize BDOS 
and select disk 

"A" 
Set DMA address 
to 8 OH 

13 



None 



None 

Side effect is that 
disk A is "logged- 
in" while all others 
are considered "off- 
line" 



CALL MON1(13,0) 



Log -in and 
select disk 
X 

14 



An integer value cor 
responding to the 
disk to log -in: 
A=0, B=l, C=2, etc. 



None 

Disk X is considered 
"on-line" and selec- 
ted for subsequent 
file operations 



CALL M0N1(14,1) 
(log-in disk "B") 



Open file 
15 



Address of the FCB 
for the file to be 
accessed 



Byte address of the 
FCB in the directory, 
if found, or 255 if 
file not present. 
The DM bytes are set 
by the BDOS. 



I = MON2(15,.FCB) 



Close file 
16 



Address of an FCB 
which has been pre- 
viously created or 
opened 



Byte address of the 
directory entry cor- 
responding to the 
FCB, or 255 if not 
present 



I = MON2(16,.FCB) 
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TABLE II (continued) 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Search for file 
17 



Address of FCB con- 
taining <filename> 
and <filetype> to 
match. ASCII "?" 
in FCB matches any 
character . 



Byte address of first 
FCB in directory that 
matches input FCB, if 
any; otherwise 255 
indicates no match. 



I = MON2(17, .FCB) 



Search for next 
occurrence 

18 



Same as above, but 
called after func- 
tion 17^ (no other 
intermediate BDOS 
calls allowed) 



Byte address of next 



I = MON2(18,.FCB) 



Delete File 
19 



Address of FCB con- 
taining <filename> 
and <filetype> of 
file to delete from 
diskette 



None 



I = MON2(19,.FCB) 



Read Next Record 
20 



Address of FCB of a 
successfully OPENed 
file, with NR set 
to the next record 
to read (see note,) 



= successful read 

1 = read past end of 

file 

2 = reading unwritten 

data in random 
access 



I = MON2(20,.FCB) 



Note 



1' 



The I/O operations transfer data to/from address 80H for the next 12 8 bytes unless 
the DMA address has been altered (see function 26) . Further, the NR field of the 
FCB is automatically incremented after the operation. If the NR field exceeds 128, 
the next extent is opened automatically, and the NR field is reset to zero. 
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TABLE II (continued) 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Write Next Record 
21 



Same as above, except 
NR is set to the next 
record to write 



= successful write 

1 = error in extend- 

ing file 

2 = end of disk data 
255 = no more dir- 
ectory space 
(see note^) 



I = MON2(21,.FCB) 



Make File 
22 



Address of FCB with 
<filename> and <file- 
type> set. Direc- 
tory entry is cre- 
ated, the file is 
initialized to empty. 



Byte address of dir- 
ectory entry alloca- 
ted to the FCB, or 
255 if no directory 
space is available 



I = MON2(22,.FCB) 



Rename FCB 
23 



Address of FCB with 
old FN and FT in 
first 16 bytes, and 
new FN and FT in 
second 16 bytes 



Address of the dir- 
ectory entry which 
matches the first 
16 bytes. The 
<filename>and <file- 
type> is altered 
255 if no match. 



I = MON2(2 3, .FCB) 



Note 



2' 



There are normally 64 directory entries available on each diskette (can be 
expanded to 255 entries), where one entry is required for the primary file, 
and one for each additional extent. 
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TABLE II (continued) 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Interrogate log- 
in vector 

24 



None 



Byte value with "1" 
in bit positions of 
"on line" disks, 
with least signi- 
ficant bit corres- 
ponding to disk "A" 



I = MON2{2 4,0 



Set DMA address 
26 



Address of 12 8 byte 
DMA buffer 



None 

Subsequent disk I/O 
takes place at spe- 
cified address in 
memory 



CALL MON1(26,2000H) 



Interrogate 
Allocation 

27 



None 



Address of the allo- 
cation vector for 
the current disk 
(usedby STATUS com- 
mand) 



M0N3: PROCEDURE (... ) 
ADDRESS; 

A = MON3(27,0) ; 



Interrogate Drive 
number 

25 



None 



Disk number of currently 
logged disk (i.e., the 
drive which will be used 
for the next disk operation 



I = MON2(25,0) ; 
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3.4 Random Access 

Recall that a single FCB describes up to a 16K segment of a 
(possibly) larger file. Random access within the first 16K seg- 
ment is accomplished by setting the NR field to the record number 
of the record to be accessed before the disk l/O takes place. 
Note, however, that if the 128th record is written, then the 
BDOS automatically increments the extent field (EX), and opens 
the next extent, if possible. In this case, the program must 
explicitly decrement the EX field and re-open the previous extent 
If random access outside the first 16K segment is necessary, 
then the extent number e be explicitly computed, given an absol- 
ute record number r as 




or equivalently. 



this extent number is then placed in the EX field before the seg- 
ment is opened. The NR value n is then computed as 



or 



n = r mod 128 



n = r AND 7FH. 



When the programmer expects considerable cross-segment accesses, 
it may save time to create an FCB for each of the 16K segments, 
open all segments for access, and compute the relevant FCB from 
the absolute record number r. 



4. SYSTEM GENERATION 

As mentioned previously, every diskette used under CP/M is assumed to 
contain the entire system (excluding transient commands) on the first two 
tracks. The operating system need not be present, however, if the diskette 
is only used as secondary disk storage on drives B, C, ..., since the CP/M 
system is loaded only from drive A. 

The CP/M file system is organized so that an IBM-compatible diskette 
from the factory (or from a vendor which claims IBM compatibility) looks 
like a diskette with an empty directory. Thus, the user must first copy 
a version of the CP/M system from an existing diskette to the first two 
tracks of the new diskette, followed by a sequence of copy operations, 
using PIP, which transfer the transient command files from the original 
diskette to the new diskette. 
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NOTE: before you begin the CP/M copy operation, read your Licensing 
Agreement. It gives your exact legal obligations when making reproductions 
of CP/M in whole or in part, and specifically requires that you place the 
copyright notice 

Copyright (c) , 1976 
Digital Research 

on each diskette which results from the copy operation. 

4.1. Initializing CP/M from an Existing Diskette 

The first two tracks are placed on a new diskette by running the tran- 
sient command SYSGEN, as described in the document "An Introduction to CP/M 
Features and Facilities." The SYSGEN operation brings the CP/M system from 
an initialized diskette into memory, and then takes the memory image and 
places it on the new diskette. 

Upon completion of the SYSGEN operation, place the original diskette 
on drive A, and the initialized diskette on drive B. Reboot the system; 
the response should be 

A> 

indicating that drive A is active. Log into drive B by typing 

B: 
and CP/M should respond with 

B> 

indicating that drive B is active. If the diskette in drive B is factory 
fresh, it will contain an empty directory. Non-standard diskettes may, 
however, appear as full directories to CP/M, which can be emptied by typing 

ERA * • *^ 

when the diskette to be initialized is active. Do not give the ERA command 
if you wish to preserve files on the new diskette since all files will be 
erased with this command. 

After examining disk B, reboot the CP/M system and return to drive A for 
further operations. 

The transient commands are then copied frcwi drive A to drive B using the 
PIP program. The sequence of commands shown below, for example, copy the 
principal programs from a standard CP/M diskette to the new diskette: 

A>PIP, 

*B : STAT . COM=STAT . COM^ 

*B :PIP .COM=PIP .COMp 

*B : LOAD . COM=LOAD . COM^ 

*B:ED.COM=ED.COM> 
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*B :ASM. COM-ASM. OOMp 

*B : SYSGEN . OOM=SYSGEN . COM^ 

*B : DDT . COM«DDT . CDM^ 

V 
A> 

The user should then log in disk B, and type the command 
DIR *.*^ 

to ensure that the files were transferred to drive B from drive A. The 
various programs can then be tested on drive B to check that they were 
transferred properly. 

Note that the copy operation can be simplified somewhat by creating 
a "submit" file which contains the copy commands. The file could be 
named GEN. SUB, for example, and might contain 

SYSGEN, 

PIP B: STAT. COM«STAT. COM, 

PIP B: PIP. C0M-PIP.COM, 

PIP B:LOAD.COM«LOAD.COM, 

PIP B : ED. COMBED. COM^ 

PIP B:ASM.COM=ASM.CO^\, 

PIP B:SYSGEN.COM=SYSGEN.COM^ 

PIP B:DDT.COM«DDT.COM^ 

The generation of a new diskette from the standard diskette is then done 
by typing simply 

SUBMIT GEN, 

5. CP/M ENTRY POINT SUMMARY 

The functions shown below sunmiarize the functions of the 
FDOS. The function number is passed in Register C (first para- 
meter in PL/M) , and the information is passed in Registers D,E 
(second PL/M parameter) . Single byte results are returned in 
Register A. If a double byte result is returned, then the high- 
order byte comes back in Register B (normal PL/M return) . The 
transient program enters the FDOS through location "entry" (see 
Section 7.) as shown in Section 2. for PL/M, or 

CALL entry 

in assembly language. All registers are altered in the FDOS. 
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Function 


Number 





System Reset 


1 


Read Console 


2 


Write Console 


3 


Read Reader 


4 


Write Punch 


5 


Write List 


6 


(not used) 


7 


Interrogate I/O Status 


8 


Alter I/O Status 


9 


Print Console Buffer 


10 


Read Console Buffer 


11 


Check Console Status 


12 


Lift Disk Head 


13 


Reset Disk System 


14 


Select Disk 


15 


Open File 


16 


Close File 


17 


Search First 


18 


Search Next 


19 


Delete File 


20 


Read Record 


21 


Write Record 


22 


Create File 


23 


Rename File 


24 


Interrogate Login 


25 


Interrogate Disk 


26 


Set DMA Address 


27 


Interrogate Allocation 



Information 



ASCII character 

ASCII character 
ASCII character 



I/O Status Byte 
Buffer Address 
Buffer Address 



Disk number 
FCB Address 



DMA Address 



Result 



ASCII character 



ASCII character 



I/O Status Byte 



True if characte: 
Ready 



Completion Code 



Login Vector 

Selected Disk 
Number 



Address of Allo- 
cation Vector 
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6. ADDRESS ASSIGNMENTS 



The standard distribution version of CP/M is organized for an Intel 
MDS microcomputer developmental system with 16K of main memory, and two 
diskette drives. Larger systems are available in 16K increments, providing 
management of 32K, 48K, and 64K systems (the largest MDS system is 62K 
since the RDM monitor provided with the MDS resides in the top 2K of the 
memory space) . For each additional 16K increment, add 4000H to the values 
of cbase and fbase. 

The address assignments are 



boot = OOOOH 
tfcb = 005CH 
tbuff* 0080H 
tbase= OlOOH 
cbase= 2900H 
fbase« 3200H 
entry* 0005H 



warm start operation 

default file control block location 

default buffer location 

base of transient progreim area 

base of console command processor 

base of disk operating system 

entry point to disk system from 

user programs 
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7. SAMPLE PROGRAMS 

This section contains two sample programs which interface with the CP/M 
operating system. The first program is written in assembly language, and 
is the source program for the DUMP utility. The second program is the CP/M 
LOAD utility, written in PL/M. 



The assembly language program begins with a number of 
tem entry points and program constants. The equate 



'equates" for sys- 



BDOS EQU 0005H 

for exapaple, gives the CP/M entry point for peripheral I/O functions. The 
defualt file control block address is also defined (FCB) , along with the 
default buffer address (BUFF) . Note that the program is set up to run at 
location lOOH, which is the base of the transient program area. The stack 
is first set-up by saving the entry stack pointer into OLDSP, and resetting 
SP to the local stack. The stack pointer upon entry belongs to the console 
command processor, and need not be saved unless control is to return to the 
CCP upon exit. That is, if the program terminates with a reboot (branch to 
location OOOOH) then the entry stack pointer need not be saved. 

The program then jumps to MAIN, past a number of subroutines which are 
listed below: 

BREAK - when called, checks to see if there is a console 

character ready. BREAK is used to stop the listing 
at the console 

PCHAR - print the character which is in register A at the 
console . 

CRLF - send carriage return and line feed to the console 

PNIB - print the hexadecimal value in register A in ASCII 
at the console 

PHEX - print the byte value (two ASCII characters) in 
register A at the console 

ERR - print error flag #n at the console , where n is 

1 if file cannot be opened 

2 if disk read error occurred 



GNB - get next byte of data from the input file. If the 
IBP (input buffer pointer) exceeds the size of the 
input buffer, then another disk record of 128 bytes 
is read. Otherwise, the next character in the buffer 
is returned. IBP is updated to point to the next 
character. 
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The MAIN program then appears, which begins by calling SETUP. The SETUP 
subroutine, discussed below, opens the input file and checks for errors. 
If the file is opened properly, the GLOOP (get loop) label gets control. 

On each successive pass through the GLOOP label, the next data byte 
is fetched using GNB and save in register B. The line addresses are listed 
every sixteen bytes, so there must be a check to see if the least signi- 
ficant 4 bits is zero on each output. If so, the line address is taken 
from registers h and 1, and typed at the left of the line. In all cases, 
the byte which was previously saved in register B is brought back to 
register A, following label NONUM, and printed in the output line. The 
cycle through GLOOP continues until an end of file condition is detected 
in DISKR, as described below. Thus, the output lines appear as 

0000 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 
0010 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 



until the end of file. 

The label FINIS gets control upon end of file. CPLF is called first 
to return the carriage from the last line output. The CCP stack pointer 
is then reclaimed from OLDSP, followed by a RET to return to the console 
command processor. Note that a JMP OOOOH could be used following the 
FINIS label, which would cause the CP/M system to be brought in again from 
the diskette (this operation is necessary only if the CCP has been over- 
layed by data areas) . 

The file control block format is then listed (FCBDN ... FCBLN) which 
overlays the fcb at location 05CH which is setup by the CCP when the 
DUMP program is initiated. That is, if the user types 

DUMP X.Y 

then the CCP sets up a properly formed fcb at location 05CH for the DUMP 
(or any other) program when it goes into execution. Thus, the SETUP sub- 
routine simply addresses this default fcb, and calls the disk system to 
open it. The DISKR (disk read) routine is called whenever GNB needs another 
buffer full of data. The default buffer at location 80H is used, along 
with a pointer (IBP) which counts bytes as they are processed. Normally, 
an end of file condition is taken as either an ASCII lAH (control-z) , or 
an end of file detection by the DOS. The file dump program, however, stops 
only on a DOS end of file. 



0100 

0005 
000F 
0014 
0002 
0001 
0006 

005C 
0080 



FILE DUMP PROGRAM, READS AN INPUT FILE AND PRINTS IN 



FCB 
BUFF 



COPYRIGHT (C) , DIGITAL RESEARCH, 1975, 1976 



ORG 

BDOS EQU 

OPENF EQU 

READF EQU 

TYPEF EQU 

CONS EQU 

BRKF EOU 



EQU 
EOU 



100H 

0005H 

15 

20 

2 

1 

11 

5CH 
80H 
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;DOS ENTRY POINT 

?FILE OPEN 

;READ FUNCTION 

;TYPE FUNCTION 

;READ CONSOLE 

; BREAK KEY FUNCTION 



(TRUE IF CHAR REA 



;FILE CONTROL BLOCK ADDRESS 
;INPUT DISK BUFFER ADDRESS 



SET UP STACK 



0100 
0103 
0104 
0107 
010A 

010D 



210000 

39 

220F01 

315101 

C3C401 



LXI 

DAD 

SHLD 

LXI 

JMP 



H,0 

SP 

OLDSP 

SP,STKTOP 

MAIN 



IBP 



VARIABLES 
DS 2 



; INPUT BUFFER POINTER 



010F 
0111 
0151 = 



0151 E5D5C5 
0154 0E0B 
0156 CD0500 
0159 CIDIEI 
015C C9 



015D E5D5C5 
0160 0E02 

0162 5F 

0163 CD0500 
0166 ClDlEl 
0169 C9 



STACK AREA 

OLDSP: DS 2 

STACK: DS 64 

STKTOP EOU $ 



SUBROUTINES 



BREAK: ;CHECK BREAK KEY (ACTUALLY ANY KEY WILL DO 
PUSH H! PUSH D! PUSH B; ENVIRONMENT SAVED 

MVI CBRKF 

CALL BDOS 

POP B! POP D! POP H; ENVIRONMENT RESTORED 
RET 

PCHAR: ? PRINT A CHARACTER 

PUSH H! PUSH Dl PUSH B; SAVED 

MVI C, TYPEF 

MOV E,A 

CALL BDOS 

POP Bl POP Di POP H; RESTORED 

RET 



016A 3E0D 
016C CD5D01 
016F 3E0A 
0171 CD5D01 
0174 C9 



CRLF: 



MVI 


A,0DH 


CALL 


PCHAR 


MVI 


A,0AH 


CALL 


PCHAR 


RET 





0175 E60F 
0177 FE0A 
0179 D28101 



PNIB: ? PRINT NIBBLE IN REG A 

ANI 0FH ;LOW 4 BITS 

CPI .10 
JNC P10 



017C C630 
017E C38301 



LESS THAN OR EQUAL TO 9 
ADI '0' 
JMP PRN 



0181 C637 P10: 
0183 CD5D01 PRN: 
0186 C9 



GREATER OR EQUAL TO 10 
ADI 'A' - 10 
CALL PCHAR 
RET 
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PHEX: ? PRINT HEX CHAR IN REG A 



0187 F5 

0188 0F 

0189 0F 
018A 0F 
018B 0F 
018C CD7501 
018F Fl 

0190 CD7501 
0193 C9 



0194 
0197 
0199 
019C 
019D 
019F 
01A2 
01A5 



CD6A01 

3E23 

CD5D01 

78 

C630 

CD5D01 

CD6A01 

C3F701 



PUSH 

RRC 

RRC 

RRC 

RRC 

CALL 

POP 

CALL 

RET 



PSW 



PNIB 

PSW 

PNIB 



jPRINT NIBBLE 



ERR: rPRIN* ERROR MESSAGE 



CALL 

MVI 

CALL 

MOV 

ADI 

CALL 

CALL 

JMP 



CRLF 
A,'#' 
PCHAR 
A,B 
'0' 

PCHAR 
CRLF 
FINIS 



GNB: 



01A8 3A0D01 
01AB FE80 
01AD C2B401 



01B0 CD1602 
01B3 AF 



01B4 5F 
01B5 1600 
01B7 3C 
01B8 320D01 



01BB E5 
01BC 218000 
01BF 19 
01C0 7E 



01C1 El 
01C2 23 
01C3 C9 



G0 



;GET NEXT BYTE 

LDA IBP 

CPI 80H 

JNZ G0 

READ ANOTHER BUFFER 



CALL 


DISKR 






XRA 


A 






;READ 


THE BYTE AT 


BUFF+REG 


A 


MOV 


E,A 






MVI 


D,0 






INR 


A 






STA 


IBP 






POINTER IS INCREMENTED 




SAVE 


THE CURRENT 


FILE ADDRESS 


PUSH 


H 






LXI 


H,BUFF 






DAD 


D 






MOV 


A,M 







BYTE IS IN THE ACCUMULATOR 

RESTORE FILE ADDRESS AND INCREMENT 
POP H 
INX H 
RET 



01C4 CDFF01 



MAIN: ; READ AND PRINT SUCCESSIVE BUFFERS 
CALL SETUP ?SET UP INPUT FILE 



01C7 3E80 
01C9 320D01 
01CC 21FFFF 



01CF CDA801 
01D2 47 



GLOOP: 



MVI A,80H 

STA IBP ; SET BUFFER POINTER TO 80H 

LXI H,0FFFFH ;SET TO -1 TO START 



CALL GNB 
MOV B,A 
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PRINT HEX VALUES 



01D3 7D 
01D4 E60F 
01D6 C2EB01 

01D9 CD6A01 



CHECK FOR LINE FOLD 

MOV A,L 

ANI 0FH ;CHECK LOW 4 BITS 

JNZ NONUM 

PRINT LINE NUMBER 

CALL CRLF 



01DC CD5101 
01DF 0F 
01E0 DAF701 

01E3 7C 

01E4 CD8701 

01E7 7D 

01E8 CD8701 

01EB 3E20 
01ED CD5D01 
01F0 78 
01F1 CD8701 



NONUM: 



CHECK FOR BREAK KEY 

CALL BREAK 

RRC 

JC FINIS ;DON'T PRINT ANY MORE 



MOV 
CALL 
MOV 
CALL 

MVI 
CALL 
MOV 
CALL 



A,H 
PHEX 
A,L 
PHEX 

A,' ' 
PCHAR 
A,B 
PHEX 



01F4 C3CF01 



01F7 CD6A01 
01FA 2A0F01 
01FD F9 
01FE C9 



005C 
005D 
0065 
0068 
006B 
007C 
007D 



EPS A: 
FINIS 



FCBDN 
FCBFN 
FCBFT 
FCBRL 
FCBRC 
FCBCR 
FCBLN 



JMP GLOOP 
;END PSA 



CALL 
LHLD 
SPHL 
RET 



END OF INPUT 

CRLF 
OLDSP 



FILE CONTROL BLOCK DEFINITIONS 



EOU 
EQU 
EQU 
EOU 
EQU 
EOU 
EOU 



FCB+0 

FCB+1 

FCB+9 

FCB+1 2 

FCB+15 

FCB+32 

FCB+33 



DISK NAME 

FILE NAME 

DISK FILE TYPE (3 CHARACTERS) 

FILE'S CURRENT REEL NUMBER 

FILE'S RECORD COUNT (0 TO 128) 

CURRENT (NEXT) RECORD NUMBER (0 TO ] 

FCB LENGTH 



01FF 115C00 
0202 0E0F 
0204 CD0500 



0207 
0209 



FEFF 
021102 



SETUP: ;SET UP FILE 

; OPEN THE FILE FOR INPUT 

LXI D,FCB 

MVI COPENF 

CALL BDOS 
; CHECK FOR ERRORS 

CPI 255 

JNZ OPNOK 







• 


BAD OPEN 




020C 


0601 




MVI 


B,l 


;OPEN ERROR 


020E 


CD9401 




CALL 


ERR 








OPNOK : 


;OPEN 


IS OK. 




0211 


AF 




XRA 


A 




0212 


327C00 




STA 


FCBCR 




0215 


C9 




RET 










DISKR: 


; READ 


DISK FILE 


RECORD 


0216 


E5D5C5 




PUSH HI PUSH Dl 


PUSH B 


0219 


115C00 




LXI 


D,FCB 




021C 


0E14 




MVI 


CREADF 




021E 


CD0500 




CALL 


BDOS 




0221 


CIDIEI 




POP B! 


POP Dl POP H 


0224 


FE00 




CPI 





?CHECK FOR ERRS 


0226 


C8 




RZ 










• 
1 


MAY BE 


EOF 




0227 


FE01 




CPI 


1 




0229 


CAF701 




JZ 


FINIS 




022C 


0602 


$ 


MVI 


B,2 


jDISK READ ERRO 


022E 


CD9401 




CALL 


ERR 
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0231 



END 
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The PL/M program which follows implements the CP/M LOAD utility. The 
function is as follows. The user types 

LOAD filename 2 

If filename. HEX exists on the diskette, then the LOAD utility reads the "hex" 
formatted machine code file and produces the file 

filename.COM 

where the COM file contains an absolute memory image of the machine code, 
ready for load and execution in the TPA. If the file does not appear on 
the diskette, the LOAD program types 

SOURCE IS READER 

and reads an Addmaster paper tape reader which contains the hex file. 

The LOAD program is set up to load and run in the TPA, and, upon com- 
pletion, return to the CCP without rebooting the system. Thus, the pro- 
gram is constructed as a single procedure called LOADCOM which takes the 
form 

0F7VH: 

LOADCOM: PROCEDURE; 
/" /* LIBRARY PROCEDURES */ 
MONl : . . . 

/* END LIBRARY PROCEDURES */ 
MOVE : . . . 
GETCHAR: ... 
PRINTNIB: ... 
PRINTHEX: ... 
PRINTADDR: ... 
RELOC : ... 
SETMEM: 
READHEX: 
READBYTE : 
READCS : 
MAKEDOUBLEi 
DIAGNOSE: 
^END RELOC; 

DECLARE STACK (16) ADDRESS, SP ADDRESS; 

SP = STACKPTR; STACKPTR » .STACK(LENGTH (STACK) ) ; 

• • • 

CALL RELOC; 

• • • 

\ STACKPTR « SP; 
V RETURN 0; 
END LOADCOM; 

; 

EOF 
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The label OFAH at the beginning sets the origin of the compilation to OFAH, 
which causes the first 6 bytes of the compilation to be ignored when loaded 
(i.e., the TPA starts at location lOOH and thus OFAH , . . . , OFFH are deleted 
from the COM. file). In a PL/M compilation, these 6 bytes are used to set up 
the stack pointer and branch around the subroutines in the program. In, this 
case, there is only one subroutine, called LOADCOM, which results in the 
following machine memory image for LOAD 

OFAH: LXI SP,plmstack ;SET SP TO DEFAULT STACK 
OFDH: JMP pastsubr ; JUMP APDUND LOADCOM 
lOOH: beginning of LOADCOM procedure 

• • • • 

end of LOADCOM procedure 
RET 

pastsubr: 
EI 
HLT 

Since the machine code between OFAH and OFFH is deleted in the load, 
execution actually begins at the top of LOADCOM. Note, however, that 
the initialization of the SP to the default stack has also been deleted; 
thus, there is a declaration and initialization of an explicit stack and 
stack pointer before the call to RELOC at the end of LOADCOM. This is 
necessary only if we wish t6 return to the CCP without a reboot operation: 
otherwise the origin of the program is set to lOOH, the declaration of 
LOADCOM as a procedure is not necessary, and termination is accomplished 
by simply executing a 

GO TO OOOOH; 

at the end of the program. Note also that the overhead for a system re- 
boot is not great (approximately 2 seconds) , but can be bothersome for 
system utilities which are used quite often, and do not need the extra 
space. 

The procedures listed in LOADCOM as "library procedures" are a standard 
set of PL/M subroutines which are useful for CP/M interface . The RELOC 
procedure contains several nested subroutines for local functions, and 
actually performs the load operation when called from LOADCOM. Control 
initially starts on line 327 where the stackpointer is saved and re- initialized 
to the local stack. The default file control block name is copied to 
another file control blocJc (SFCB) since two files may be open at the same 
time. The program then calls SEARCH to see if the HEX file exists; if not, 
then the high speed reader is used. If the file does exist, it is opened for 
input (if possible) . The filetype COM is moved to the default file control 
block area, and any existing copies of filename.COM files are removed from 
the diskette before creating a new file. The MAKE operation creates a new 
file, and, if successful, RELOC is called to read the HEX file and produce 
the COM file. At the end of processing by RELOC, the COM file is closed 
(line 350) . Note that the HEX file does not need to be closed since it 
was opened for input only. The rlata written to a file is not permanently 
recorded until the file is succeB&ifully closed. 
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Disk input characters are read through the procedure GETCHAR on line 
137. Although the DMA facilities of CP/M could be used here, the GETCHAR 
procedure instead uses the default buffer at location 80H and moves each 
buffer into a vector called SBUFF (source buffer) as it is read. On exit, 
the GETCHAR procedure returns the next input character and updates the 
source buffer pointer (SBP) . 

The SETMEM procedure on line 191 performs the opposite function from 
GETCHAR. The SETMEM procedure maintains a buffer of loaded machine code 
in pure binary form which acts as a "window" on the loaded code. If there 
is an att«npt by RELOC to write below this window, then the data is ignored. 
If the data is within the window, then it is placed into MBUFF (memory 
buffer) . If the data is to be placed above this window, then the window 
is moved up to the point where it would include the data address by writing 
the memory image successively (by 128 byte buffers), and moving the base 
address of the window. Using this technique, the pjrogrammer can recover 
from checksum errors on the high-speed reader by stopping the reader, 
rewinding the tape for some distance, then restarting LOAD (in this case, 
LOADing is resumed by interrupting with a NOP instruction) . Again, the 
SETMEM procedure uses the default buffer at location BOH to perform the 
disk output by moving 128 byte segments to 80H through OFFH before each 
write. 
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3Z 

0FAH: DECLARE BDOS LITERALLY '0005H'; 
/* TRANSIENT COMMAND LOADER PROGRAM 

COPYRIGHT (C) DIGITAL RESEARCH 
JUNE, 1975 
*/ 

LOADCOM: PROCEDURE BYTE; 

DECLARE FCBA ADDRESS INITIAL ( 5CH) ; 
DECLARE FCB BASED FCBA (33) BYTE; 

DECLARE BUFFA ADDRESS INITIAL ( 80H) , /* I/O BUFFER ADDR 

BUFFER BASED BUFFA (128) BYTE; 

DECLARE SFCB(33) BYTE, /* SOURCE FILE CONTROL BLOCK * 

BSIZE LITERALLY '1024', 
EOFILE LITERALLY 'lAH', 
S6UFF (BSIZE) BYTE /* SOURCE FILE BUFFER */ 

INITIAL (EOFILE) , 
RFLAG BYTE, /* READER FLAG */ 

SBP ADDRESS; /* SOURCE FILE BUFFER POINTER 

/* LOADCOM LOADS TRANSIENT COMMAND FILES TO THE DISK F 
CURRENTLY DEFINED READER PERIPHERAL. THE LOADER PLACE 
CODE INTO A FILE WHICH APPEARS IN THE LOADCOM COMMAND 
/* **************** LIBRARY PROCEDURES FOR DISKIO ******* 



MONl: PROCEDURE (F, A) ; 
DECLARE F BYTE, 
A ADDRESS; 
GO TO BDOS; 
END MONl; 

M0N2: PROCEDURE (F, A) BYTE; 
DECLARE F BYTE, 
A ADDRESS; 
GO TO BDOS; 
END M0N2; 

READRDR: PROCEDURE BYTE; 

/* READ CURRENT READER DEVICE */ 
RETURN MON2(3,0) ; 
END READRDR; 

DECLARE 

TRUE LITERALLY '1', 

FALSE LITERALLY '0', 

FOREVER LITERALLY 'WHILE TRUE', 

CR LITERALLY '13', 
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LF' LITERALLY ' 1 ' , ' 
WHAT LITERALLY '63'? 

PRINTCHAR: PROCEDURE (CHAR) ; 33 

DECLARE CHAR BYTE; 
CALL MONK 2, CHAR) ; 
END PRINTCHAR; 

CRLF: PROCEDURE; 

CALL PRINTCHAR (CR) ; 
CALL PRINTCHAR ( LF ) ; 
END CRLF; 

PRINT: PROCEDURE (A) ; 

DECLARE A ADDRESS; 

/* PRINT THE STRING STARTING AT ADDRESS A UNTIL THE 

NEXT DOLLAR SIGN IS ENCOUNTERED */ 

CALL CRLF; 

CALL MONK 9, A) ; 

END PRINT; 

DECLARE DCNT BYTE; 

INITIALIZE: PROCEDURE; 
CALL MON1{13,0) ; 
END INITIALIZE; 

SELECT: PROCEDURE (D) ; 
DECLARE D BYTE; 
CALL MONK 14, D) ; 
END SELECT; 

OPEN: PROCEDURE (FCB) ; 

DECLARE FCB ADDRESS; 
DCNT = MON2(15,FCB) ; 
END OPEN; 

CLOSE: PROCEDURE (FCB) ; 

DECLARE FCB ADDRESS; 
DCNT = MON2(16,FCB) ; 
END CLOSE; 

SEARCH: PROCEDURE (FCB) ; 
DECLARE FCB ADDRESS; 
DCNT = MON2(17,FCB); 
END SEARCH; 

SEARCHN: PROCEDURE; 

DCNT = MON2(18,0) ; 
END SEARCHN; 

DELETE: PROCEDURE (FCB) ; 
DECLARE FCB ADDRESS; 
CALL M0N1(19,FCB) ; 
END DELETE; 

DISKREAD: PROCEDURE (FCB) BYTE; 
DECLARE FCB ADDRESS; 
RETURN MON2(20,FCB) ; 
END DISKREAD; 
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DISKWRITE: PROCEDURE (FCB) BYTE; 
DECLARE FCB. ADDRESS; 

RETURN M0N2 (21, FCB) ; M 

END DISKWRITE; 

MA~Ke71?R0CEDURE(FCBJ ; 

DECLARE FCB ADDRESS; 
DCNT = MON2(22,FCB) ; 
END MAKE; 

RENAME: PROCEDURE (FCB) ; 
DECLARE FCB ADDRESS; 
CALL MONK 23, FCB) ; 
END RENAME; 

/* ******************* END OF LIBRARY PROCEDURES ******** 



MOVE: PROCEDURE (S,D,N) ; 

DECLARE (S,D) ADDRESS, N BYTE, 
A BASED S BYTE, B BASED D BYTE; 

DO WHILE (N:=N-1) <> 255; 

B = A; S=S+1; D=D+1; 

END; 
END MOVE; 

GETCHAR: PROCEDURE BYTE; 

/* GET NEXT CHARACTER */ 

DECLARE I BYTE; 

IF RFLAG THEN RETURN READRDR; 

(SBP i^ SBP+1) <= LAST(SBUFF) THEN 
RETURN SBUFF(SBP) ; 
OTHERWISE READ ANOTHER BUFFER FULL 
DO SBP » TO LAST(SBUFF) BY 128; 
IF (I:=DISKREAD(.SFCB)) = THEN 

CALL MOVE(80H,.SBUFF(SBP) ,80H) ; ELSE 

DO; IF lOl THEN CALL PRINT (.'DISK READ ER 



IF 



/• 
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SBUFF(SBP) « EOFILE; 

SBP = LAST(SBUFF) ; 

END; 
END; 
SBP = 0; RETURN SBUFF; 
END GETCHAR; 



DECLARE 



STACKPOINTER LITERALLY ' STACKPTR ' ; 



PRINTNIB: PROCEDURE (N) ; 
DECLARE N BYTE; 

IF N > 9 THEN CALL PRINTCHAR(N+ 'A'~10) ; ELSE 

CALL PRINTCHAR(N+'0') ; 
END PRINTNIB; 



PRINTHEX: PROCEDURE (B) ; 
DECLARE B BYTE; 

CALL PRINTNIB(SHR(B,4)) 
END PRINTHEX; 



CALL PRINTNIB (B AND 0FH) 
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PRINTADDR: PROCEDURE (A); 
DECLARE A ADDRESS? 

CALL PRINTHEX(HIGH(A) ) ; CALL PRINTHEX (LOW (A) ) ; 
END PRINTADDR; 



/* INTEL HEX FORMAT LOADER */ 

RELOC: PROCEDURE? 

DECLARE (RL, CS , RT) BYTE? 
DECLARE 

LA ADDRESS*. 
TA ADDRESS, 
SA ADDRESS, 
FA ADDRESS, 
NB ADDRESS, 
SP ADDRESS, 
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/* LOAD ADDREaS */ 

/* TEMP ADDRESS */ 

/* START ADDRESS */ 

/* FINAL ADDRESS */ 

/* NUMBER OF BYTES LOADED */ 

/* STACK POINTER UPON ENTRY TO PEL 



hBUFF{256) BYTE, 

P BYTE, 

L ADDRESS? 

SETMEM: PROCEDURE (B) ? 

/* SET MBUFF TO B AT LOCATION LA MOD LENGTH (MBUFF) 

DECLARE (B,I) BYTE? 

IF LA < L THEN /* MAY BE A RETRY */ RETURN? 

DO WHILE LA > L + LAST(MBUFF)? /* WRITE A PARA 

DO I = TO 127? /* COPY INTO BUFFER */ 

BUFFER(I) = MBUFF (LOW (L) ) ? L = L + 1; 

END? 
/* WRITE BUFFER ONTO DISK */ 
P = P + 1? 
IF DISKWRITE(FCBA) <> THEN 

DO? CALL PRINT(. 'DISK WRITE ERROR$ ') ? 

HALT ? 

/* RETRY AFTER INTERRUPT NOP */ 

L = L - 128? 

END? 
END? 
MBUFF (LOW (LA) ) = B? 
END SETMEM? 

READHEX: PROCEDURE BYTE? 

/* READ ONE HEX CHARACTER FROM THE INPUT */ 

DECLARE H BYTE? 

IF (H := GETCHAR) - '0' <= 9 THEN RETURN H - '0'? 

IF H - 'A' > 5 THEN GO TO CHARERR? 

RETURN H - 'A' + 10? 

END READHEX? 

READBYTE: PROCEDURE BYTE? 

/* READ TWO HEX DIGITS */ 

RETURN SHL (READHEX, 4) OR READHEX? 

END READBYTE? 

READCS: PROCEDURE BYTE? 

/* READ BYTE WHILE COMPUTING CHECKSUM */ 
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DECLARE B BYTE; 

CS « CS + (B := READBYTE) ? 

RETURN B; 

END READCS; 3<> 

MAKE$DOUBLE: PROCEDURE (H,L) ADDRESS; 

/* CREATE A BOUBLE BYTE VALUE FROM TWO SINGLE BYTE 

DECLARE (H,L) BYTE; 

RETURN SHL (DOUBLE (H) ,8) OR L; 

END MAKE$DOUBLE; 

DIAGNOSE: PROCEDURE; 

DECLARE M BASED TA BYTE; 

NEWLINE: PROCEDURE; 

CALL CRLF; CALL PRINTADDP (TA) ; CALL PRINTCHAR( ' : ') 

CALL PRINTCHAR( ' ') ; 
END NEWLINE; 

/* PRINT DIAGNOSTIC INFORMATION AT THE CONSOLE */ 

CALL PRINT(.'LOAD ADDRESS $'); CALL PRINTADDR (TA) ; 
CALL Pl^INT(. 'ERROR ADDRESS $'); CALL PRINTADDR (LA) ? 

CALL PRINT (. 'BYTES READ:$'); CALL NEWLINE; 

DO WHILE TA < LA? 

IF (LOW(TA) AND 0FH) = THEN CALL NEWLINE; 

CALL PRINTHEX(MBUFF(TA-L)) ; TA=TA+1 ; 

CALL PRINTCHAR(' ') ; 

END; 
CALL CRLF; 
HALT; 
END DIAGNOSE; 



/* INITIALIZE */ 

SA, FA, NB = 0; 

SP = STACKPOINTER; 

P = 0; /* PARAGRAPH COUNT */ 

TA,LA,L = 100H; /* BASE ADDRESS OF TRANSIENT ROUTINES 

IF FALSE THEN 

CHARERR: /* ARRIVE HERE IF NON-HEX DIGIT IS ENCOU 

DO; /* RESTORE STACKPOINTER */ STACKPOINTER = SP; 
CALL PRINT (.'NON-HEXADECIMAL DIGIT ENCOUNTERED $') 

CALL DIAGNOSE; 
END; 



/* READ RECORDS UNTIL :00XXXX IS ENCOUNTERED */ 

DO FOREVER; 

/* SCAN THE : */ 

DO WHILE GETCHAR <> ' ; ' ; 

END; 
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/* SET GHEGK SUM TO ZERO, AND SAVE THE RECORD LENG 

CS = 0j 

/* MAY BE THE END OF TAPE */ ^„ 

IF (RL := READCS) = THEN ' 

GO TO FIN; 
NB = NB + RL? 

TA, LA = MAKE$DOUBLE (READCS, READCS) ; 
IF SA = THEN SA = LA; 



/* READ THE RECORD TYPE (NOT CURRENTLY USED) */ 
RT = READCS; 

/* PROCESS EACH BYTE */ 

DO WHILE (RL := RL - 1) <> 255; 

CALL SETMEM (READCS) ; LA = LA+1 ; 

END; 
IF LA > FA THEN FA = LA - 1; 

/* NOW READ CHECKSUM AND COMPARE */ 
IF CS + READBYTE <> THEN 
DOl_^CMI^JLRXNT UlgHggJK sua. SE^ 

CALL DIAGNOSE; 

END; 
END; 

FIN: 

/* EMPTY THE BUFFERS */ 

TA = LA; 

DO WHILE L < TA; 

CALL SETMEM (0); LA = LA+1; 

END; 
/* PRINT FINAL STATISTICS */ 

CALL PRINT(. 'FIRST ADDRESS $'); CALL PRINTADDR (SA) 
CALL PRINT(.'LAST ADDRESS $') ; CALL PRINTADDR (FA) 
CALL PRINT (. 'BYTES READ $'); CALL PRINTADDR (NB) 
CALL PRINT (. 'RECORDS WRITTEN $'); CALL PRINTHEX(P) 
CALL CRLF; 

END RELOC ; 

/* ARRIVE HERE FROM THE SYSTEM MONITOR, READY TO READ THE 



/* SET UP STACKPOINTER IN THE LOCAL AREA */ 
DECLARE STACK(16) ADDRESS, SP ADDRESS; 
SP = STACKPOINTER; STACKPOINTER = .STACK (LENGTH (STACK) ) ; 

SBP = LENGTH (SBUFF) ; 

/* SET UP THE SOURCE FILE */ 
CALL MOVE(FCBA,.SFCB,33) ; 
CALL MOVE(. ('HEX',0) ,.SFCB(9) ,4) ; 
CALL SEARCH (.SFCB) ; 
IF (RFLAG := DCNT = 255) THEN 

CALL PRINT(. 'SOURCE IS READER$') ; ELSE 
DO; CALL PRINT (. 'SOURCE IS DISK$'); 



00337 3 CALL OPEN (.SFCB) ; 

00338 3 IF DCNT = 255 THEN CALL PRINT (. '-CANNOT OPEN SOURC 
E$'); 

00339 3 END; ^ 

00340 2 CALL CRLF; ^ 

00341 2 

00342 2 CALL MOVE(. 'COM',FCBA+9,3) ; 

00343 2 

00344 2 /* REMOVE ANY EXISTING FILE BY THIS NAME */ 

00345 2 CALL DELETE (FCBA) ; 

00346 2 /* THEN OPEN A NEW FILE */ 

00347 2 CALL MAKE (FCBA) ; FCB(32) « 0; /* CREATE AND SET NEXT RECORD */ 

00348 2 IF DCNT = 255 THEN CALL PRINT(.'N0 MORE DIRECTORY SPACE$ ' 
) ; ELSE 

00349 2 DO; CALL RELOC ; 

00350 3 CALL CLOSE (FCBA) ; 

00351 3 IF DCNT = 255 THEN CALL PRINT (. 'CANNOT CLOSE FILE$ 

'); 

00352 3 END; 

00353 2 CALL CRLF; 

00354 2 

00355 2 /* RESTORE STACKPOINTER FOR RETURN */ 

00356 2 STACKPOINTER = SP; 

00357 2 RETURN 0; 

00358 2 END LOADCOM; 

00359 1 

00360 1 EOF 



